<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<title>run_test</title>
<link rel="stylesheet" href="../../../boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="../../../index.html" title="Boost.Test">
<link rel="up" href="../rt_param_reference.html" title="Runtime parameters reference">
<link rel="prev" href="result_code.html" title="result_code">
<link rel="next" href="save_pattern.html" title="save_pattern">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../../boost.png"></td>
<td align="center"><a href="../../../../../../../index.html">Home</a></td>
<td align="center"><a href="../../../../../../../libs/libraries.htm">Libraries</a></td>
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
<td align="center"><a href="../../../../../../../more/index.htm">More</a></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="result_code.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../rt_param_reference.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="save_pattern.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="boost_test.utf_reference.rt_param_reference.run_test"></a><a class="link" href="run_test.html" title="run_test"><code class="computeroutput"><span class="identifier">run_test</span></code></a>
</h4></div></div></div>
<p>
          Parameter <span class="emphasis"><em>run_test</em></span> allows to filter which test units
          to execute during testing. The <span class="emphasis"><em>Unit Test Framework</em></span>
          supports both "selection filters", which allow to select which
          test units to enable from the set of available test units, and "disabler
          filters", which allow to disable some test units. The <span class="emphasis"><em>Unit
          Test Framework</em></span> also supports enabling/disabling test units at
          compile time. These settings identify the default set of test units to
          run. Parameter <span class="emphasis"><em>run_test</em></span> is used to change this default.
          This parameter is repeatable, so you can specify more than one filter if
          necessary. It is also possible to use the ':' for separating each filter
          which can be used for filtering the tests with the environment variable
          <code class="computeroutput"><span class="identifier">BOOST_TEST_RUN_FILTERS</span></code>
          (as it cannot be repeated like <code class="computeroutput"><span class="special">--</span><span class="identifier">run_test</span></code>).
        </p>
<p>
          More details about practical application of this parameter resides in
          <a class="link" href="../../runtime_config/test_unit_filtering.html" title="Test unit filtering">test unit
          filtering</a> section.
        </p>
<h5>
<a name="boost_test.utf_reference.rt_param_reference.run_test.h0"></a>
          <span class="phrase"><a name="boost_test.utf_reference.rt_param_reference.run_test.acceptable_values"></a></span><a class="link" href="run_test.html#boost_test.utf_reference.rt_param_reference.run_test.acceptable_values">Acceptable
          values</a>
        </h5>
<p>
          <a class="link" href="../rt_param_reference.html#regular_param_value">String</a> value representing single
          filter or a set of filters separated by ':'. The following grammar productions
          describe the syntax of filters:
        </p>
<pre class="programlisting"><span class="identifier">filter_set</span>    <span class="special">::=</span> <span class="special">(</span><span class="identifier">filter</span> <span class="char">':'</span><span class="special">)*</span> <span class="identifier">filter</span>
<span class="identifier">filter</span>        <span class="special">::=</span> <span class="identifier">relative_spec</span><span class="special">?</span> <span class="identifier">test_set</span>
<span class="identifier">relative_spec</span> <span class="special">::=</span> <span class="char">'+'</span> <span class="special">|</span> <span class="char">'!'</span>
<span class="identifier">test_set</span>      <span class="special">::=</span> <span class="identifier">label</span> <span class="special">|</span> <span class="identifier">path</span>
<span class="identifier">label</span>         <span class="special">::=</span> <span class="char">'@'</span> <span class="identifier">identifier</span>
<span class="identifier">path</span>          <span class="special">::=</span> <span class="special">(</span><span class="identifier">suite</span> <span class="char">'/'</span><span class="special">)?</span> <span class="identifier">pattern_list</span>
<span class="identifier">pattern_list</span>  <span class="special">::=</span> <span class="special">(</span><span class="identifier">pattern</span> <span class="char">','</span><span class="special">)*</span> <span class="identifier">pattern</span>
<span class="identifier">suite</span>         <span class="special">::=</span> <span class="special">(</span><span class="identifier">pattern</span> <span class="char">'/'</span><span class="special">)*</span> <span class="identifier">pattern</span>
<span class="identifier">pattern</span>       <span class="special">::=</span> <span class="char">'*'</span><span class="special">?</span> <span class="identifier">identifier</span> <span class="char">'*'</span><span class="special">?</span>
</pre>
<div class="caution"><table border="0" summary="Caution">
<tr>
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../../doc/src/images/caution.png"></td>
<th align="left">Caution</th>
</tr>
<tr><td align="left" valign="top"><p>
            the <code class="computeroutput"><span class="identifier">pattern_list</span></code> above
            indicates test unit inside the same test suite given by <code class="computeroutput"><span class="identifier">suite</span></code>. This means that the syntax "<code class="computeroutput"><span class="special">--</span><span class="identifier">run_test</span><span class="special">=</span><span class="identifier">suite1</span><span class="special">/</span><span class="identifier">suite2</span><span class="special">/</span><span class="identifier">A</span><span class="special">,</span><span class="identifier">B</span><span class="special">,</span><span class="identifier">C</span></code>"
            runs the test cases <code class="computeroutput"><span class="identifier">A</span></code>,
            <code class="computeroutput"><span class="identifier">B</span></code> and <code class="computeroutput"><span class="identifier">C</span></code>
            that are <span class="bold"><strong>inside</strong></span> <code class="computeroutput"><span class="identifier">suite1</span><span class="special">/</span><span class="identifier">suite2</span></code>.
            In order to indicate several test units that are not siblings, either
            repeat the <code class="computeroutput"><span class="special">--</span><span class="identifier">run_test</span></code>
            or use <code class="computeroutput"><span class="special">:</span></code> to separate the
            filters.
          </p></td></tr>
</table></div>
<p>
          Regarding the meaning of these values <a class="link" href="../../runtime_config/test_unit_filtering.html#ref_command_line_control">see
          here</a>.
        </p>
<h5>
<a name="boost_test.utf_reference.rt_param_reference.run_test.h1"></a>
          <span class="phrase"><a name="boost_test.utf_reference.rt_param_reference.run_test.command_line_syntax"></a></span><a class="link" href="run_test.html#boost_test.utf_reference.rt_param_reference.run_test.command_line_syntax">Command
          line syntax</a>
        </h5>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem">
              <code class="computeroutput"><span class="special">--</span><span class="identifier">run_test</span><span class="special">=&lt;</span><span class="identifier">test</span>
              <span class="identifier">unit</span> <span class="identifier">filter</span>
              <span class="identifier">spec</span><span class="special">&gt;</span></code>
            </li>
<li class="listitem">
              <code class="computeroutput"><span class="special">-</span><span class="identifier">t</span>
              <span class="special">&lt;</span><span class="identifier">test</span>
              <span class="identifier">unit</span> <span class="identifier">filter</span>
              <span class="identifier">spec</span><span class="special">&gt;</span></code>
            </li>
</ul></div>
<h5>
<a name="boost_test.utf_reference.rt_param_reference.run_test.h2"></a>
          <span class="phrase"><a name="boost_test.utf_reference.rt_param_reference.run_test.environment_variable"></a></span><a class="link" href="run_test.html#boost_test.utf_reference.rt_param_reference.run_test.environment_variable">Environment
          variable</a>
        </h5>
<pre class="programlisting"><span class="identifier">BOOST_TEST_RUN_FILTERS</span>
</pre>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2001-2022 Boost.Test contributors<p>
        Distributed under the Boost Software License, Version 1.0. (See accompanying
        file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
      </p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="result_code.html"><img src="../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../rt_param_reference.html"><img src="../../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../../index.html"><img src="../../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="save_pattern.html"><img src="../../../../../../../doc/src/images/next.png" alt="Next"></a>
</div>
</body>
</html>
